POV-Ray will substitute the %s with the scene name in the command. The scene name is the Input_File_Name or +i setting with any drive, directory or extension removed. For example:
is stripped down to the scene name "waycool" which results in...
In an animation it may be necessary to have the exact output file name with the frame number included. The string %o will substitute the output file name. Suppose you want to save your output files in a zip archive using pkzip. You could do...
After rendering frame 12 of myscene.pov, POV-Ray would shell to the operating system with pkzip -m myscene mysce012.tga. The -m switch in pkzip moves mysce012.tga to myscene.zip and removes it from the directory. Note that %o includes frame numbers only when in an animation loop. During the Pre_Scene_Command and Post_Scene_Command, there is no frame number so the original, unnumbered Output_File_Name is used. Any User_Abort_Command or Fatal_Error_Command not inside the loop will similarly give an unnumbered %o substitution.
Here is the complete list of substitutions available for a common string.
%o | Output file name with extension and embedded frame number if any |
%s | Scene name derived by stripping path and ext from input name |
%n | Frame number of this frame |
%k | Clock value of this frame |
%h | Height of image in pixels |
%w | Width of image in pixels |
%% | A single % sign. |
1) All INI and switches are processed just once. 2) Open any text output streams and do Create_INI if any 3) Pre_Scene_Command executed if any 4) Loop through frames (or just do once on non-animation) a) Pre_Frame_Command executed if any b) Parse entire scene file, open output file and read settings, turn on display, render the frame, destroy all objects, textures etc., close output file, close display. c) Post_Frame_Command executed if any d) Go back to 4 a until all frames done 5) Post_Scene_Command executed if any 6) Exit POV-Ray.
If the user interrupts processing, the User_Abort_Command, if any, is executed. User aborts can only occur during the parsing and rendering parts of step 4b above.
If a fatal error occurs that POV-Ray notices, the Fatal_Error_Command, if any, is executed. Sometimes an unforeseen bug or memory error could cause a total crash of the program in which case there is no chance to shell out. Fatal errors can occur just about anywhere including during the processing of switches or INI files. If a fatal error occurs before POV-Ray has read the Fatal_Error_Command string then obviously no shell can occur.
Note that the entire scene is re-parsed for every frame. Future versions of POV-Ray may allow you to hold over parts of a scene from once frame to the next but for now, it starts from scratch ever time. Note also that the Pre_Frame_Command occurs before the scene is parsed. You might use this to call some custom scene generation utility before each frame. This utility could rewrite your .POV or .INC files if needed. Perhaps you will want to generate new .GIF or .TGA files for image maps or height fields on each frame.
Pre_Scene_Return=s | Set pre scene return actions |
Pre_Frame_Return=s | Set pre frame return actions |
Post_Scene_Return=s | Set post scene return actions |
Post_Frame_Return=s | Set post frame return actions |
User_Abort_Return=s | Set user abort return actions |
Fatal_Error_Return=s | Set fatal return actions |
Note no +/- switches are available for these options. They cannot be used from the command line. They may only be used from INI files.
Most operating systems allow application programs to return an error code if something goes wrong. When POV-Ray executes a shell command, it can make use of this error code returned from the shell process and take some appropriate action if the code is zero or non-zero. POV-Ray itself returns such codes. It returns 0 for success, 1 for fatal error and 2 for user abort.
The actions are designated by a single letter in the different *_Return=s options. The possible actions are:
I | ignore the code |
S | skip one step |
A | all steps skipped |
Q | quit POV-Ray immediately |
U | generate a user abort in POV-Ray |
F | generate a fatal error in POV-Ray |
For example if your Pre_Frame_Command calls a program which generates your height field data and that utility fails, then it will return a non-zero code. We would probably want POV-Ray to abort as well. The option Pre_Frame_Return=F will cause POV-Ray to do a fatal abort if the Pre_Frame_Command returns a non-zero code.
Sometimes a non-zero code from the external process is a good thing. Suppose you want to test if a frame has already been rendered. You could use the S action to skip this frame if the file is already rendered. Most utilities report an error if the file is not found. For example the command pkzip -v myscene mysce012.tga tells pkzip you want to view its catalog for myscene.zip for the file mysce012.tga. If the file isn't in the archive, pkzip returns a non-zero code.
However we want to skip if the file is found. Therefore we need to reverse the ACTION so it skips on zero and doesn't skip on non-zero. To reverse the zero vs non-zero triggering of an action, precede it with a - sign. (Note a ! will also work. ! is used in many programming languages as a "not" operator).
Pre_Frame_Return=S will skip if the code shows error (non-zero) and will proceed normally on no error (zero).
Pre_Frame_Return=-S will skip if there is no error (zero) and will proceed normally if there is an error (non-zero).
The default for all shells is I which means ignore the return action no matter what. POV-Ray simply proceeds with whatever it was doing before the shell command. The other actions depend upon the context. You may want to refer back to the animation loop sequence chart in the previous section. The action for each shell is as follows...
On return from any User_Abort_Command, if there is an action triggered and you have specified...
F | then turn this user abort into a fatal error. Do the Fatal_Error_Command, if any. Exit POV-Ray with error code 1. |
S, A, Q, or U | then proceed with the user abort. Exit POV-Ray with error code 2. |
On return from any Fatal_Error_Command, proceed with the fatal error no matter what. Exit POV-Ray with error code 1.
On return from any Pre_Scene_Command, Pre_Frame_Command, Post_Frame_Command or Post_Scene_Commands if there is an action triggered and you have specified...
F | then generate a fatal error. Do the Fatal_Error_Command, if any. Exit POV-Ray with an error code 1. |
U | then generate a user abort. Do the User_Abort_Command, if any. Exit POV-Ray with an error code 2. |
Q | then quit POV-Ray immediately. Acts as though POV-Ray never really ran. Do no further shells, (not even Post_Scene_Command) and exit POV-Ray with an error code 0. |
On return from a Pre_Scene_Command, if there is an action triggered and you have specified...
S | then skip rendering all frames. Acts as though the scene completed all frames normally. Do not do any Pre_Frame_Command or Post_Frame_Commands. Do the Post_Scene_Command, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip step #4. |
A | then skip all scene activity. Works exactly like Q quit. On the earlier chart this means skip to step #6. |
On return from a Pre_Frame_Command, if there is an action triggered and you have specified...
S | then skip only this frame. Acts as though this frame never existed. Do not do the Post_Frame_Command. Proceed with the next frame. On the earlier chart this means skip steps #4b and #4c but loop back as needed in #4d. |
A | then skip rendering this frame and all remaining frames. Acts as though the scene completed all frames normally. Do not do any further Post_Frame_Commands. Do the Post_Scene_Command, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip the rest of step #4 and proceed at step #5. |
On return from a Post_Frame_Command, if there is an action triggered and you have specified...
S | then skip rendering all remaining frames. Acts as though the scene completed all frames normally. Do the Post_Scene_Command, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip the rest of step #4 and proceed at step #5. |
A | same as S for this shell command. |
On return from any Post_Scene_Command, if there is an action triggered and you have specified...
Sor A | same as I for this shell command. |
Here is a description of each stream.
BANNER: This stream displays the program's sign-on banner, copyright, contributor's list, and some help screens. It cannot be turned off or directed to a file because most of this text is displayed before any options or switches are read. Therefore you cannot use an option or switch to control it. There are switches which display the help screens. They are covered in section "Help Screen Switches" .
DEBUG: This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to display messages from within their scene files. See "Text Message Streams" for details on this feature. This stream may be turned off and/or directed to a text file.
FATAL: This stream displays fatal error messages. After displaying this text, POV-Ray will terminate. When the error is a scene parsing error, you may be shown several lines of scene text that leads up to the error. This stream may be turned off and/or directed to a text file.
RENDER: This stream displays information about what options you have specified to render the scene. It includes feedback on all of the major options such as scene name, resolution, animation settings, anti-aliasing and others. This stream may be turned off and/or directed to a text file.
STATISTICS: This stream displays statistics after a frame is rendered. It includes information about the number of rays traced, the length of time of the processing and other information. This stream may be turned off and/or directed to a text file.
STATUS: This stream displays one-line status messages that explain what POV-Ray is doing at the moment. On some systems this stream is displayed on a status line at the bottom of the screen. This stream cannot be directed to a file because there is generally no need to. The text displayed by the Verbose option or +V switch is output to this stream so that part of the status stream may be turned off.
WARNING: This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-Ray can continue to render the scene. You will be informed if POV-Ray has made any assumptions about your scene so that it can proceed. In general any time you see a warning, you should also assume that this means that future versions of POV-Ray will not allow the warned action. Therefore you should attempt to eliminate warning messages so your scene will be able to run in future versions of POV-Ray. This stream may be turned off and/or directed to a text file.
Debug_Console=bool | Turn console display of debug info text on/off |
+GD | Same as Debug_Console=On |
-GD | Same as Debug_Console=Off |
Fatal_Console=bool | Turn console display of fatal error text on/off |
+GF | Same as Fatal_Console=On |
-GF | Same as Fatal_Console=Off |
Render_Console=bool | Turn console display of render info text on/off |
+GR | Same as Render_Console=On |
-GR | Same as Render_Console=Off |
Statistic_Console=bool | Turn console display of statistic text on/off |
+GS | Same as Statistic_Console=On |
-GS | Same as Statistic_Console=Off |
Warning_Console=bool | Turn console display of warning text on/off |
+GW | Same as Warning_Console=On |
-GW | Same as Warning_Console=Off |
All_Console=bool | Turn on/off all debug, fatal, render, statistic and warning text to console. |
+GA | Same as All_Console=On |
-GA | Same as All_Console=Off |
You may suppress the output to the console of the Debug, Fatal, Render, Statistic or Warning text streams. For example the Statistic_Console=off option or the -GS switch can turn off the Statistic stream. Using on or +GS you may turn it on again. You may also turn all 5 of these streams on or off at once using the All_Console option or +GA switch.
Note these options take effect immediately when specified. Obviously any Error or Warning messages that might occur before the option is read, it will not be affected.
Debug_File=true | Echo debug info text to DEBUG.OUT |
Debug_File=false | Turn off file output of debug info |
Debug_File=file | Echo debug info text to file |
+GDfile | Both Debug_Console=On, Debug_File=file |
-GDfile | Both Debug_Console=Off, Debug_File=file |
Fatal_File=true | Echo fatal text to FATAL.OUT |
Fatal_File=false | Turn off file output of fatal |
Fatal_File=file | Echo fatal info text to file |
+GFfile | Both Fatal_Console=On, Fatal_File=file |
-GFfile | Both Fatal_Console=Off, Fatal_File=file |
Render_File=true | Echo render info text to RENDER.OUT |
Render_File=false | Turn off file output of render info |
Render_File=file | Echo render info text to file |
+GRfile | Both Render_Console=On, Render_File=file |
-GRfile | Both Render_Console=Off, Render_File=file |
Statistic_File=true | Echo statistic text to STATS.OUT |
Statistic_File=false | Turn off file output of statistics |
Statistic_File=file | Echo statistic text to file |
+GSFile | Both Statistic_Console=On, Statistic_File=file |
-GSFile | Both Statistic_Console=Off, Statistic_File=file |
Warning_File=true | Echo warning info text to WARNING.OUT |
Warning_File=false | Turn off file output of warning info |
Warning_File=file | Echo warning info text to file |
+GWfile | Both Warning_Console=On, Warning_File=file |
-GWfile | Both Warning_Console=Off, Warning_File=file |
All_File=true | Echo all debug, fatal, render, statistic and warning text to ALLTEXT.OUT |
All_File=false | Turn off file output of all debug, fatal, render, statistic and warning text |
All_File=file | Echo all debug, fatal, render, statistic and warning text to file |
+GWfile | Both All_Console=On, All_File=file |
-GWfile | Both All_Console=Off, All_File=file |
You may direct a copy of the text streams to a text file for the Debug, Fatal, Render, Statistic or Warning text streams. For example the Statistic_File=ssssss option or the +GSsssssss switch. If the string ssssss is true or any of the other valid true strings then that stream is redirected to a file with a default name. Valid "true" values are true, yes, on or 1. If the value is false, the direction to a text file is turned off. Valid "false" values are false, no, off or 0. Any other string specified turns on file output and the string is interpreted as the output file name.
Similarly you may specify such a true, false or file name string after a switch such as +GSfile. You may also direct all 5 of these streams to the same file using the All_File option or +GA switch. You may not specify the same file for two or more streams because POV-Ray will fail when it tries to open or close the same file twice.
Note these options take effect immediately when specified. Obviously any Error or Warning messages that might occur before the option is read, it will not be affected.